home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 4 / Apprentice-Release4.iso / Source Code / Libraries / Graphic Elements 3 / GESound / GESound README next >
Text File  |  1995-05-25  |  4KB  |  130 lines
  1. GESound Module
  2.  
  3. An asynchronous sound player for use with Graphic Elements
  4.  
  5. Copyright 1995 by Al Evans. All rights reserved.
  6.  
  7. -----
  8.  
  9. The GESound module strives to provide an application program interface to asynchronous sound
  10. playback which is as easy to use as the Graphic Elements API itself.
  11.  
  12. At startup, the application program initializes the module by requesting a GESoundsRec
  13. initialized for the maximum number of sounds it will play at the same time.
  14.  
  15.  
  16.     GESoundPtr GEInitSounds(short nSoundChannels);
  17.  
  18. Where
  19.  
  20.     - nSoundChannels is the maximum number of sounds which will play simultaneously.
  21.     
  22. -----
  23.  
  24. Once each time through the main event loop, the application passes this record to
  25. GESoundMaintenance(). This routine starts any sounds scheduled to begin "now", and
  26. cleans up after any sounds which have finished playing.
  27.  
  28.     void GESoundMaintenance(GESoundPtr sounds);
  29.     
  30. Where
  31.  
  32.     - sounds is a pointer to a GESoundsRec obtained by calling GEInitSounds().
  33.  
  34. -----
  35.  
  36. To play a sound, the application program calls GEScheduleSound(), passing it the resource
  37. number of the 'snd ' resource it wishes to play, the number of milliseconds to wait before
  38. playing the sound, and the priority level of the request. If too many sounds are scheduled
  39. for the number of channels available, those with higher priorities take precedence.
  40.  
  41.     OSErr GEScheduleSound(GESoundPtr sounds, short sndResID, short priority, 
  42.                                 unsigned long msDelay);
  43.                                 
  44. Where
  45.  
  46.     - sounds is a pointer to a GESoundsRec obtained by calling GEInitSounds(),
  47.     
  48.     - sndResID is the number of the 'snd ' resource the application wishes to play,
  49.     
  50.     - priority is a number representing how "important" this sound is to the application,
  51.     
  52.     - msDelay is the number of milliseconds from the time GEScheduleSound() is called
  53.       to wait before playing the sound.
  54.  
  55. -----
  56.                                 
  57. When it is completely finished playing sounds, the application calls GEDisposeSounds() to
  58. free all memory, sound channels, and other resources used by the GESound module.
  59.  
  60.     void GEDisposeSounds(GESoundPtr sounds);
  61.     
  62. Where
  63.  
  64.     - sounds is a pointer to a GESoundsRec obtained by calling GEInitSounds().
  65.  
  66. ----
  67.  
  68. The GESounds module also includes calls to permit the application program to control 
  69. and obtain information about sound playback.
  70.  
  71. Playback can be enabled and disabled for an entire GESoundsRec, for example in response
  72. to the user's selection of a menu item.
  73.  
  74.     void GEnableSound(GESoundPtr sounds, Boolean enableIt);
  75.  
  76. Where
  77.  
  78.     - sounds is a pointer to a GESoundsRec obtained by calling GEInitSounds().
  79.     
  80. -----
  81.     
  82. The data for a particular sound can be locked in memory (when it is likely to be used
  83. repeatedly) or made purgeable (when the likelihood of repeated use has ended).
  84.  
  85.     void GEHoldSound(GESoundPtr sounds, short sndResID, Boolean keepInMemory);
  86.     
  87. Where
  88.  
  89.     - sounds is a pointer to a GESoundsRec obtained by calling GEInitSounds(),
  90.     
  91.     - keepInMemory is true to lock the sound data in memory or false to make it purgeable.
  92.     
  93. -----
  94.  
  95. The application program can determine whether a specified sound is currently being played.
  96.  
  97.     Boolean GESoundPlaying(GESoundPtr sounds, short sndResID);
  98.     
  99. Where
  100.  
  101.     - sounds is a pointer to a GESoundsRec obtained by calling GEInitSounds(),
  102.     
  103.     - sndResID is the resource number of the sound for which information is desired.
  104.     
  105. -----
  106.     
  107. The application program can stop the playback of a specified sound.
  108.  
  109.     void GEStopOneSound(GESoundPtr sounds, short sndResID);
  110.     
  111. Where
  112.  
  113.     - sounds is a pointer to a GESoundsRec obtained by calling GEInitSounds(),
  114.     
  115.     - sndResID is the resource number of the sound which is to be stopped.
  116.     
  117. -----
  118.     
  119. The application program can stop all sounds which are currently playing. (This is
  120. done automatically if the program calls GEnableSound() with enableIt == false).
  121.     
  122.     void GEStopAllSounds(GESoundPtr sounds);
  123.  
  124. Where
  125.  
  126.     - sounds is a pointer to a GESoundsRec obtained by calling GEInitSounds().
  127.  
  128.  
  129.  
  130.